babbf6
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,69 +27,73 @@
import org.springframework.util.Assert;
 import org.springframework.util.ObjectUtils;
 
 /**
- * Holder that combines a {@link org.springframework.core.io.Resource}
- * with a specific encoding to be used for reading from the resource.
+ * Holder that combines a {@link Resource} descriptor with a specific encoding
+ * or {@code Charset} to be used for reading from the resource.
  *
- * <p>Used as argument for operations that support to read content with
- * a specific encoding (usually through a {@code java.io.Reader}).
+ * <p>Used as an argument for operations that support reading content with
+ * a specific encoding, typically via a {@code java.io.Reader}.
  *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 1.2.6
  * @see java.io.Reader
+ * @see java.nio.charset.Charset
  */
 public class EncodedResource {
 
 	private final Resource resource;
 
-	private String encoding;
+	private final String encoding;
 
-	private Charset charset;
+	private final Charset charset;
 
 
 	/**
-	 * Create a new EncodedResource for the given Resource,
-	 * not specifying a specific encoding.
-	 * @param resource the Resource to hold
+	 * Create a new {@code EncodedResource} for the given {@code Resource},
+	 * not specifying an explicit encoding or {@code Charset}.
+	 * @param resource the {@code Resource} to hold; never {@code null}
 	 */
 	public EncodedResource(Resource resource) {
-		Assert.notNull(resource, "Resource must not be null");
-		this.resource = resource;
+		this(resource, null, null);
 	}
 
 	/**
-	 * Create a new EncodedResource for the given Resource,
-	 * using the specified encoding.
-	 * @param resource the Resource to hold
+	 * Create a new {@code EncodedResource} for the given {@code Resource},
+	 * using the specified {@code encoding}.
+	 * @param resource the {@code Resource} to hold; never {@code null}
 	 * @param encoding the encoding to use for reading from the resource
 	 */
 	public EncodedResource(Resource resource, String encoding) {
-		Assert.notNull(resource, "Resource must not be null");
-		this.resource = resource;
-		this.encoding = encoding;
+		this(resource, encoding, null);
 	}
 
 	/**
-	 * Create a new EncodedResource for the given Resource,
-	 * using the specified encoding.
-	 * @param resource the Resource to hold
-	 * @param charset the charset to use for reading from the resource
+	 * Create a new {@code EncodedResource} for the given {@code Resource},
+	 * using the specified {@code Charset}.
+	 * @param resource the {@code Resource} to hold; never {@code null}
+	 * @param charset the {@code Charset} to use for reading from the resource
 	 */
 	public EncodedResource(Resource resource, Charset charset) {
+		this(resource, null, charset);
+	}
+
+	private EncodedResource(Resource resource, String encoding, Charset charset) {
+		super();
 		Assert.notNull(resource, "Resource must not be null");
 		this.resource = resource;
+		this.encoding = encoding;
 		this.charset = charset;
 	}
 
-
 	/**
-	 * Return the Resource held.
+	 * Return the {@code Resource} held by this {@code EncodedResource}.
 	 */
 	public final Resource getResource() {
 		return this.resource;
 	}
 
 	/**
-	 * Return the encoding to use for reading from the resource,
+	 * Return the encoding to use for reading from the {@linkplain #getResource() resource},
 	 * or {@code null} if none specified.
 	 */
 	public final String getEncoding() {
@@ -97,17 +101,17 @@
public class EncodedResource {
 	}
 
 	/**
-	 * Return the charset to use for reading from the resource,
+	 * Return the {@code Charset} to use for reading from the {@linkplain #getResource() resource},
 	 * or {@code null} if none specified.
 	 */
 	public final Charset getCharset() {
 		return this.charset;
 	}
 
-
 	/**
 	 * Determine whether a {@link Reader} is required as opposed to an {@link InputStream},
-	 * i.e. whether an encoding or a charset has been specified.
+	 * i.e. whether an {@linkplain #getEncoding() encoding} or a {@link #getCharset() Charset}
+	 * has been specified.
 	 * @see #getReader()
 	 * @see #getInputStream()
 	 */
@@ -116,10 +120,12 @@
public class EncodedResource {
 	}
 
 	/**
-	 * Open a {@code java.io.Reader} for the specified resource,
-	 * using the specified encoding (if any).
+	 * Open a {@code java.io.Reader} for the specified resource, using the specified
+	 * {@link #getCharset() Charset} or {@linkplain #getEncoding() encoding}
+	 * (if any).
 	 * @throws IOException if opening the Reader failed
 	 * @see #requiresReader()
+	 * @see #getInputStream()
 	 */
 	public Reader getReader() throws IOException {
 		if (this.charset != null) {
@@ -134,10 +140,11 @@
public class EncodedResource {
 	}
 
 	/**
-	 * Open an {@code java.io.InputStream} for the specified resource,
-	 * typically assuming that there is no specific encoding to use.
+	 * Open a {@code java.io.InputStream} for the specified resource, ignoring any
+	 * specified {@link #getCharset() Charset} or {@linkplain #getEncoding() encoding}.
 	 * @throws IOException if opening the InputStream failed
 	 * @see #requiresReader()
+	 * @see #getReader()
 	 */
 	public InputStream getInputStream() throws IOException {
 		return this.resource.getInputStream();
@@ -150,9 +157,10 @@
public class EncodedResource {
 			return true;
 		}
 		if (obj instanceof EncodedResource) {
-			EncodedResource otherRes = (EncodedResource) obj;
-			return (this.resource.equals(otherRes.resource) &&
-					ObjectUtils.nullSafeEquals(this.encoding, otherRes.encoding));
+			EncodedResource that = (EncodedResource) obj;
+			return (this.resource.equals(that.resource) &&
+					ObjectUtils.nullSafeEquals(this.charset, that.charset) &&
+					ObjectUtils.nullSafeEquals(this.encoding, that.encoding));
 		}
 		return false;
 	}
